# API 接口文档

域名地址：`https://play.gxx12138.space/api`

> 说明：本接口用于学生游戏分数提交与排行榜查询，所有接口返回统一 JSON 格式。
> 
> 

## 公共返回格式

|字段|类型|说明|
|---|---|---|
|code|int|状态码：200 成功，400 参数错误，500 服务异常|
|msg|string|提示信息，成功时部分接口可省略|
|业务字段|any|接口自定义返回数据|

---

## 1\. 提交分数接口

### 接口地址

`POST /submit`
完整 URL：`https://play.gxx12138.space/api/submit`

### 接口说明

提交学生游戏玩家名称、分数、提交时间。

> 学生姓名放在 URL 查询参数；玩家、分数、时间放在请求 Body JSON 内。
> 
> 

### 请求参数

#### Query 参数（URL 参数）

|参数名|类型|是否必填|说明|
|---|---|---|---|
|user\_name|string|是|学生自己姓名，作为学生域标识|

#### Body JSON 参数

|参数名|类型|是否必填|说明|
|---|---|---|---|
|player|string|是|学生创建游戏的玩家名称|
|score|int|是|游戏分数，非负整数|
|date|string|是|提交时间，格式 `yyyy-MM-dd HH:mm:ss`|

### 请求示例

```http
POST https://play.gxx12138.space/api/submit?user_name=关习习
Content-Type: application/json

{
    "player": "玩家001",
    "score": 95,
    "date": "2026-09-24 16:30:00"
}
```

### 成功返回示例

```json
{
    "code": 200,
    "msg": "提交成功"
}
```

### 错误返回示例

```json
{
    "code": 400,
    "msg": "body缺少 player / score / date"
}
```

---

## 2\. 查询 TOP10 排行榜接口

### 接口地址

`GET /result`
完整 URL：`https://play.gxx12138.space/api/result`

### 接口说明

根据学生姓名，查询该学生域内，分数前 10 名玩家，按分数**降序排列**。

### 请求参数

#### Query 参数（URL 参数）

|参数名|类型|是否必填|说明|
|---|---|---|---|
|user\_name|string|是|学生姓名|

### 请求示例

```http
GET https://play.gxx12138.space/api/result?user_name=关习习
```

### 成功返回示例

```json
{
    "code": 200,
    "user_name": "张三",
    "top10": [
        {
            "player": "玩家001",
            "score": 95,
            "date": "2026-09-24 16:30:00"
        },
        {
            "player": "玩家002",
            "score": 82,
            "date": "2026-09-24 16:35:00"
        }
    ]
}
```

### 错误返回示例

```json
{
    "code": 400,
    "msg": "缺少query参数 user_name（学生姓名）"
}
```

---

## 状态码说明

|code|含义|
|---|---|
|200|请求成功|
|400|参数缺失 / 参数格式错误|
|500|服务器内部异常（数据库连接失败等）|

## 调用注意事项

1. POST `/submit` 请求必须设置请求头 `Content-Type: application/json`

2. date 时间格式严格要求 `yyyy-MM-dd HH:mm:ss`

3. 排行榜最多返回 10 条记录，分数相同按数据库原始顺序返回